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ABOUT THIS BOOK 


The ISAN file Maneger i¢ a set of precedures and functions that you use to 
create and manipulate indexed. sequential-access date files. (ISAM refers to 
the fale access method -- the Indexed, Sequential-Access Method,) The 
procedures are written (and described here) in the Pascal~-86 language, but 
they are usable from programs in other GRib supported languages. 


The first chapter talks generaliy about the procedures and functions and what 
they do. It also describes the structure of the data files created. Chapter 
2 explains the format this book uses to give you procedure information. 
Chapter 3 lists the detailed procedures alphabetically for easy look-up. 


Appendix @ contains the error codes (and associated messages) returned by the 
status parameter. Appendix B gives you run-time information (names of files 
toa load and inctude). For general information on the programmer's interface, 
loading. linking, and compiling, see the GRiD Program Development Buide and 
the appropriate language manual, 


The ISAN File Manager comprises both procedures and functions. (A function is 
like a procedure except that it returns information "in its name," in 
addition to information returned by its parameters.) Nevertheless, this 
manual frequently uses the word “procedures” to refer to a combination of 
procedures and functions 


O 
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CHAPTER i: QVERVIEW OF THE ISAM FILE MANAGER 


This chapter provides a quick overview of the capabilities and operation 
of the ISAM File Manager. 


PROCEDURES FOR WORKING WITH INDEXED DATA FILES 


The ISAM File Manager allows yeu to create and access indexed 
(keyed) data files programmaticaliy, in essence, lets you build 
and use your own database. Figure I-1 loosely depicts the 
relationship between your program, the ISAM File Manager, and 
the data and key files youcreate. Table 1-1 summarizes what 
the procedures do. 


Figure 1-1. Programmatic Access of Data Files 
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Table t-1. Summary of Procedures 


ISAMCreate Creates a data file in which all records have 


the same number of fields (columns) and the 
fields are of variable length. 


ISAMAttach ; Makes a data file and its associated key 
files available to your program. 

ISAMOpen Opens and allocates memory for an attached 
data file. 


ISAMCreateIndex 


ISAMOpen Index 


ISAMAppendRecord 


For an open data file, designates a column to 
be a key column. The file manager creates a 
key file containing the alphabetically or 
numerically sorted values in that coluan. 


Qpens and allocates memory for a key file. 


Adds a record to the end of a data file. 
When there are no records, adds the first 
one, 


ISAMRep! aceRecord Replaces the content of a record in a data 
file. 

ISAMDel eteRecord Deletes the content of a record from a data 
file (marks it deleted). 


TSAMChangeColumns 


Inserts, deletes, duplicates or moves 
columns in an open data file. 


TSAMRead Copies a record from an open data file. 


Finds the first record with a certain value 
in a certain column and returns the I.D. of 
the record. 


ISAMFindNext Finds the next record and returns the content 
of a specified column and the record 1.D. 


ISAMFindGeneric Finds the first record with a column value 
greater than or equal to a certain value and 


returns the value and the record I.D. 
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Table 1~1 (Continued). Summary of Procedures 


ISAMResetFile 


ISAMGetStatus . 
Physically removes records marked deleted 


TSAMCompress 
fram an open data file. 
ISAMDecodeError Returns a message explaining an error code. 


ISAMC] oseIndex Closes a key file and deallocates the memory 
associated with it. 

ISAMDeleteIndex Deletes a key file associated with a data 
file. 
Closes and deallocates memory assigned ta 
a data file. 


TSAMDetach Makes a data file and its associated 


key files unavailable to your program. 
J ismesit | Closes and detaches data and key files. 
USING THE PROCEDURES 


Your language manual contains specific information on calling 
procedures from your particular language. Since you need to pay 
attention to differences between your program language and 
Pascal-86, such as differences in data types, we recommend you 
see that information. For example, if you are programming in 
Fortran-86, see the Fortran-86 User’s Guide, Appendix H. 


Moves the file pointer to the beginning of a 
data file or to the first key in a key file. 


Returns the number of columns, number of key 
columns, and number of records deleted or 
replaced since the last compression. 


In general, you use the ISAM File Manager procedures to create 
and load data files, then perform quick, keved access. 


Your first task is ta create the data file {ISAMCreate). If you 
are qoing to use it immediately, vou allocate memory space to it 
with a call to ISAMOpen. To use a file that is already created, 
you need only attach CISAMAttach) and open it. (The attach 
associates the already created file with your program.) 


Both ISAMCreate and ISAMAttach return a file number (#ileNumber) 
that you use in all other Procedure calls to identify the data 
file. 


Your second task is to determine which, if any, columns of the 
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The ISAM File Manager takes the vaiues in that key column, sorts them 
alphabetically or numerically depending on the column format, and places them 
in a key file. Each key in the key file is associated, via a record I.D., 
with the appropriate data file record, Later, when you search the coluan 
(ISAMFind or TSAMFindGeneric) in preparation for some activity, the sorted 
order of the key file makes the search go faster, especially if the data file 
contains a large number of records. 


You may designate that the key column accept only unique keys. When keys are 
nonunique, the search finds the first occurrence and returns an indication of 
whether the next record is different; if it isn’t, you must call ISAMFindNext 
to get the record I.D. of the second occurrence, 


The third task is the real work. Use ISAMAppendRecord to add content to the 
data file; ISAMFind, ISANFindNext, and ISAMFindGeneric to locate records in 
various ways; ISAMResetFile to reset the file pointer; and ISANReplaceRecord, 
ISAMRead, ISAMDeleteRecord, ISAMChangeColumns to manipulate the records. Key 
files are automatically updated when you alter records in the data file. 


The fourth and last task, as you may guess, involves shutting down work. Use 
TSAMGetStatus to return the number of records actually deleted, then decide 
whether to compress the file or not. ISAMCompress physically removes records 
you deleted (marked deleted), but it takes a little time. ISAMClose 
deallocates the memory space allocated to the data file, and ISAMCloseIndex 
does the same thing for a key file; you may wish to use these closes to save 
space while you keep the files “in the wings." ISAMDetach closes AND makes 
the data file (AND its key files) unavailable to your program; ISAMExit does 
everything ISAMDetach does AND does not return to your progran, 


The set of procedures you use on any occasion depends, of course, on what you 
want to do; the two sequences below illustrate typical tasks. 
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To create an indexed data file and enter data in it, you might cali this 
© sequence of procedures. 


o ISANCreate, to create your data file (attachment is automatic). 


o ISAMOpen, to open the file and allocate memory space, 


o ISAMCreateIndex, to establish a field (column) as a key column. The ISAM 
File Manager creates a sorted key file of the values in the key column, 


o ISAMOpenIndex, to open the key file and allocate it memory space, 
o ISAMAppendRecord, to insert the first record. 
o ISAMAppendRecords, to insert subsequent records. 
co ISAMDetach, to close and detach the data file and its associated key file. 
Later, to amend the same database, you might use the following sequence of 
procedures: 
o ISAMAttach, to make the data file and key file available to your program. 
o ISAMOpen, to open and allocate memory space to the data file. 
ed o ISAMOpenindex, to open and allocate memory space to the key file. 
o ISAMFindGeneric, to find a record in a key column. 
o ISAMReplaceRecord, to replace the found record. 
o ISAMChangeColumns, to delete a column. 
o ISAMFind, to find a record with a certain value in a column. 
o ISAMDeleteRecord, to delete the found record. 


o ISAMExit, to detach and close the data and key files. 
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FILE STRUCTURE 


The data file that you create (a cal] to ISAMCreate) is conceptually a matrix 
in which each row will hold a record and each column contains related record 
fields, You do not designate the length of the record fields; instead, the 

ISAM File Manager, dynamically handies any length field. Figure 1-2 shows the 


empty matrix. nf 
Relotid Fxsdel- 


Figure 1-2. The ISAM Data File Structure 


To add content to the database, you call ISAMAppendRecord for 
each record to be added. The input parameter NewRecord is a 
pointer to a string containing the record. The data in the 
string must be of the form 


The ISAM File Manager takes each TAB character to represent the end of data in 
a column and each CARRIAGE-RETURN/LINE-FEED (CR/LF) to represent the end of 
the record. The record you append must have the correct number of columns for 
the data file. 


Not coincidentally, this file structure is compatible with 6RiD System's 
"Interchange File Format." The Interchange File Format makes it easy to move 
data from one application to another, for example from a GRiDPLAN worksheet to 
a GRIDFILE database. It is possible that you may wish to access records from 
an application, for example from a GRiDFILE database, using an ISAM 
application program of your own. When you do so, these records will contain 
TABs and CARRIAGE-RETURNS/LINE-FEEDS, leaving you to ensure only that the 
records contain the correct number of columns for the destination database 
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application program of your own. When you do so. these records 
will contain TABs and CARRIAGE-RETURMS/LINE-FEEDs, leaving you 
to ensure only that the records contain the correct number of 
columns for the destination database. 
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CHAPTER 2: UNDERSTANDING THE PROCEDURE INFORMATION 


This chapter explains what you need to know to call a procedure. You need 
to understand the procedure’s operation and its return vakue, and you need 
to know the parameters, their order, their pass methods and directions, 
and their data types. Figure 2-1 shows the ISAMCreate function in the 
format this manual uses to give you procedure information. 


(Alenamer StringPtrs 
passeord: Stringntrs 
numberColusns: Integers 
VAR status: Mord): Integer) 


Creates 0 file with the name you specify in fileNeee, the 
astword you specify in passeord, and the number ef colusns you 
Specify in numberColuans. If a file of the sane name and 
Password exists already, it is deleted, 


7 


Returns the file nuaber, a type Integer, that the systee 
ausigns. fAvsociste « variable with the 
it in ather calle to identify the date 


Figure 2-1. Procedure (Function) Format 
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Pascal Procedure (Function) Declaration 


Procedure 


This is the declaration in the Pascal-86 language. If you are a 
Pascal programmer, you construct your cali to the procedure by 
referring to this declaration. It tells you the procedure name 
and the order and types of the parameters. 


(Function? Name 


Procedures are listed by name in Chapter 3. You use the name in 
your call to the procedure. 


Procedure (Function) Operation 


® 


The procedure operation describes what work the procedure does. 


Function Return 


© 


Parameter 


© 


Functions pass information back to your program in the form of a 
function return. It is up to you to associate a variable with 
the function name. The variable accepts the output information. 
In ISAMCreate, a system assigned file number of the data type 
Integer is returned. Do not confuse the function return with 
ouput parameters (discussed below) which also return information 
to your program. 


Names 


In the table of parameter information, the first column contains 
procedure parameter names in their correct calling order. Each 
time you call the procedure, parameters in your caJl factual 
parameters) are matched to the procedure parameters -- your 
first parameter to the procedure’s first, the second to its 
second, and so on. Your call to the procedure, then, must 
contain actual parameters in the same order as the procedure 
parameters. 


The Status parameter is the last one for almost every procedure. 
It returns information on the success of the operation (see 
Appendix A for a list of the status return numbers and their 
meanings). 


2-2 Procedure Information 


Pass Method 


© The second column tells you a parameter’s pass method, how it 
passes information to the procedure, or, in the case of an 
output parameter, how the procedure passes information to your 
program. 


There are two methods of passing information -- by value and by 
reference. When a parameter is passed by value, the actual 
parameter is evaluated and the resulting actual value is passed. 
When a parameter is passed by reference, its address is passed. 
In the procedure declaration, a parameter that is passed by 
reference is preceded by "VAR." 


In/Out 


© The third column telis you whether a parameter is an input 
parameter ‘one that passes information to the procedure) or an 

output parameter (one that passes information from the procedure 
to your program). Some parameters are both input and output 
parameters; in such a case, you use the parameter to pass a 
value to the procedure, and the procedure returns a different 
value to your program. All output parameters are passed by 
reference, and all input parameters are passed by value. 
Parameters that are both input and output are passed by 
reference. 


Data Type 


The fourth column contains a parameter’s data type. Because 
these procedures are shown in Pascal-86, the data types are 
Pascal data types. If you are accessing the procedures fram 
some other language, @.g-, PL/M-B6, you must match the 
parameters with variables in your program that have compatible 
data types. To determine what data types in your language 
correspond to the procedure types in column 4, see your Janguage 
manual. Table 2-1 lists Pascal data types and, since some of 
you program in PL/M-86. shows corresponding data types in 
PL/M-B6. 
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fable 2-1. Data Types for ISAM Procedure Parameters 


Pascal Type 
Boolean Simple ordinal. Predetined values 
ere FALSE (0) and TRUE (1). 
Integer Simple ordinal] of two bytes in the 
range -32768 through +52767, 
LongInt 
in the ranae 0 through 65535. 
Unsigned. 


fn enumerated type defined (0 .. 255). 
& pointer to a record type defined: Pointer 
String = Record 
Len: Integers 
Max: Integers 
Dummy: Byte 
Chars: ARRAY [Ci..maxInt] of Char; 
END; 
Byte = 0... 255; 
StringPtr = “String; 
A StringPtr is a dynamic structure 
allocated by the NewString procedure and 
disposed of by the FreeString procedure 
described in the Common Code Manual). The 
calling program must never change the Max 
element as it is the maximum amount of 
memory allocated to the string. 


2-4 Procedure Information 


Simple ordinal of four bytes in the 
range -2,157,483,647 through 
42,147, 483,697. Signed. 


Simple ordinal of two bytes. Inteaers 


StringPtr 


CHAPTER 3: ISAM FILE MANAGER PROCEDURES 


This chapter lists the ISAM File Manager Procedures in alphabetical order. 
Use it to look up the details of a procedure as you construct a call. 


ISAMAppendRecor d 


PROCEDURE ISAMAppendRecord (fileNumber: Integer; 
newRecord: StringPtr; 
VAR recordID: LongInt; 
VAR status: Word); 


OPERATION 


Inserts a new record at the end of the open data file you 
identify and returns the 1.D. number of the new record. All key 
files associated with the data file must also be open so that 
they can be updated. The record appended, pointed to by 
newRecord, must have the correct number of columns for the data 
file (the record consists of character data separated into 
columns by TAB characters and a final 
CARRTAGE-RETURN/LINE-FEED). Successive calls to 
ISAMAppendRecord load a new data file. 


fileNumber Value Integer 


newRecord Value StringPtr 


recordID Reference LongInt 


status Reference Word 


Procedures 3-1 


ISAMAttach 


FUNCTION ISAMAttach (fileName: StringPtr: 
password: StringPtr; 
VAR Status: Word): 
Integer: 


OPERATION 


Makes a previously created data file and its key files available 
to your program. You must provide the proper password. You 
must attach a file before you can open it. 


FUNCTION RETURN 
Returns the file number (data type Integer) assigned by the 


system. Associate a variable with the procedure name, then use 
it in other calls to identify the data file. 


| Parameter | _ Pass Method Data Type 


fileName Value StringPtr 


password Value StringPtr 


status Reference Word 


NOTE: If the file does not rave a patswerd, the password value 
should be zero (0), 


3-2 Procedures 


ISAMCHhangeColumms 


OPERATION 


PROCEDURE fSAMChangeColumns (fileNumber: Integer; 
fromColumn: Integer; 
toColumn =: Integer; 
columns: Integers 
eraseUrignal: Boolean; 
VAR status: Word); 


Inserts, deletes, duplicates or moves columns in the open data 
file vou identify. To delete columns, place a negative number 
in columns; that number of columns will be deleted beginning at 
the column identified by toColumn. To insert columns, place a 
positive number in columns and zera in fromColumn; the specified 
number of columns will be inserted beginning at the column 
specified in toColumn. 


To duplicate columns, place a positive number in columns and the 
column number of the first source column in fromColumn; the 
number of columns specified will be duplicated beginning at the 
column specified by toColumn. The setup to move columns is 
identical to duplicate except that you set eraseDriginal true; 
the number of columns specified will be moved to the column 
spetified by toColumn and deleted at fromColumn. 


When you insert or delete a column, the ISAM File Manager 
updates every record in the file and compresses the file. Since 


characers are added or deleted from each record, record I.D.’5 
obtained previously are no tonger valid. 


fileNumber Value Integer 
fromColumn Value Integer 
toCelumn Value Integer 


columns Value Integer 


eraseOriginal Value Boolean 


Status Reference Word 


Procedures 3-3 


ISAMC1 ose 


PROCEDURE ISANClose (fileNumber: Integer 
VAR status: Word); 


OPERATION 
Closes and deallocates memory for the open data file that you 


identify. | This procedure does not close the key files 
associated with the data file. 


[Pass Method _| 
Integer 
Word 


PROCEDURE ISAMCloseIndex (fileNumber: Integer; 
columnNumber: Integer; 
VAR status: Word); 


fileNumber 


Value 


status Reference 


ISAMC1 ose Index 


OPERATION 


Closes and deallocates memory for the open key file associated 
with the column and data file you identify. 


fileNumber Value 


columnNumber Value 


status Reference 


3-4 Procedures 
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ISAMCompress 


PROCEDURE ISAMCompress (fileNumber: Integer; 
VAR status: Word); 


OPERATION 


Physically removes all the records that are marked deleted, 
compressing the data file you identify. 


Pass Method In/Out Data Type 


Input Integer 
Gutput Word 


fileNumber Value 


status Reference 


ISAMCreate 


FUNCTION ISAMCreate (fileName: StringPtr; 
Password: Stringptrs 
numberColumns: Integers 
VAR status: Word): Integer; 


OPERATION 


Creates a file with the name you specify in fileName, the 
password you specify in password, and the number of columns you 
specify in numberColumns. If a file of the same name and 
password exists already, it is deleted. 


FUNCTION RETURN 
Returns the file number, a type Integer, that the system 


assigns. Associate a variable with the procedure name, then use 
it in other calis to identify the data file. 


filename Value 


password Value 


numberCol umns Value Integer 


status Reference Word 


Procedures 3-5 


ISAMCr eat eIndex 


PROCEDURE ISAMCreateIndex (fileNumber: Integer; 
columnNumber: Integer; ‘ 
keysAreUnique: Bool ean; 8 
format: Byte; 
VAR status: Word); 


OPERATION 


Creates an alphabetically or numerically sorted file for the key 
column and data file you specify in columnNumber and fileNumber. 
Set format to 0 for alphanumeric keys or to ! for numeric keys. 
You may ask that the keys be unique (TRUE) or not unique 
(FALSE). If you ask that keys be unique and there already are 
Nonunigue values in the column, an error is returned and the key 
file is not created. 


Pass Nethod Data Type 


fileNumber Value Integer 


columnNumber Value Integer 


keysAreUni que Value Boolean 


format Value Byte 


status Reference Word 8 


3-6 Procedures 


oO 


ISAMDecodeEr ror 
FUNCTION ISAMDecodeError (status: Word): StringPtr; 
OPERATION 
Locates the message associated with an ISAM error code or an 
operating system error code. ISAM error codes, in the range 
2500 - 2514, are described in Appendix A. 
FUNCTION RETURN 


Returns a pointer to a string containing the message. 
Pass Methad | In/ut 
es ee eee 


ESAMDeleteIndex 


PROCEDURE ISAMDeleteIndex (fileNumber: Integer; 
columnNumber: Integer; 
VAR status: Word); 


OPERATION 
Deletes the sorted key file previously created for the 


identified column and data file. The data file must be 
attached, but it need not be open. 


Pass Nethod | _In/Dut 


fileNumber Value Integer 


columnNumber Value Integer 


status Reference Wor 
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ISAMDe! et eRecord 


PROCEDURE ISAMDeleteRecord (fileNumber: Integer; 
recordID: LongInt; 
VAR status: Word); 


‘OPERATION 


Marks a record (row) in the identified open data file as 
deleted. All keys associated with the data cells in this row 
are also marked deleted. (Data is not physically removed until 
the data file is compressed.) 


tn/Out_| Data Type 


fileNumber ‘Value Integer 


recordID Value Longint 


status Reference Word 


ISAMDet ach 


PROCEDURE ISAMDetach (fileNumber: Integer; 
VAR status: Word); 


OPERATION 


Makes the previously attached data file and its associated key 
files unavailable to your program. In addition, ISAMDetach 
closes the data file and closes and detaches the key files. 


| Parameter __| In/Out [| Data Type 


Input Integer 
Output Word 


#ileNumber Value 


status 


Reference 


3-8 Procedures 


ISAMExit 


O 


OPERATION 


PROCEDURE ISAMEni ts 


Closes and detaches all attached data files and key files and 
exits your program. Since this procedure does not return to 
your program, it should be the last one you call. 


ISAMFind 


OPERATION 


PROCEDURE ISAMFind (fileNumber: Inteqer 
columnNumber: Integer; 
valueToFind: StringPtr; 
VAR unique: UniqueTypes; 
format: Byte; 

VAR recordID: LongInt; 
VAR status: Word); 


Finds the first record with a value in the data file 
you identify and returns the I.D. of the record. 
is a key column, the Unique parameter returns 
key is a duplicate, a Dif it is not. When the column is not a 
key column, Unique returns a 2. When the column is not a key 
column, specify an alphabetic (0) or numeric (1) search using 
the format parameter. 


Pass Method In/Out 


Value 


and coluan 
If the column 
@ if the next 


fileNumber Integer 


col umnNumber Value 


Integer 


valueToFind Value StringPtr 


unique Reference UniqueTypet 


format Value Byte 


recordID Reference LongInt 


status Reference Word 


¥ One-byte enumerated type defined (Key IsUni que, KeyIsNotUni que, 
Unknown). 


Pe aradiene 


ISAMFindGeneric 


OPERATION 


FUNCTION ISAMFindGeneric (#ileNumber: Integer; 
columnNumber: Integer; 
valueToFind: StringPtr; 

VAR unique: UniqueTypet; 
VAR recordID: Longint; 
VAR status: Word): StringPtr; 


Finds the value in a key column that is greater than or equal ta 
a value you specify in the valueToFind parameter. Returns the 
J.D. of the record containing the value. Unique returns 0 if 
the next key is a duplicate, 1 if it is not. The column you 
identify must be a key ‘column. 


FUNCTION RETURN y 
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Returns a pointer to the string containing the key value found. 
You must subsequently free the string by calling FreeString (see 


the Common Code Reference Manual). 
Pass Method 


#ileNumber Value Integer 


columnNumber Value Integer 


valueToFind Value StringPtr 


unique Reference UniqueTypet 


recordID Reference LongInt 


status Reference Word 


% A one-byte enumerated type defined to be (KeyIsUnique, 
Keyl sNotUni que, Unknown). 


Procedures 


ISAMFlushALIBuffers 


FUNCTIGN ISAMF3ushAllBaffers (cenn: Word; 
VAR etatuss Ward): StrirgPtre: 


GPERATION 


Writes the contents of 1) burfers in memory taliccated mtn 
TSAMGpen and [3PMupeniIngex: currently assigqrec ‘s 2 file cut to the 
file residing a deyice-tubject. it can thus be thougkt of as a 
precautionary lo that le veu save the contents of file buffers 
mthout going cough 2 "“close-open' sequence, 


Perameter Fass Method In/det Data Type 
filellumber Velve Input Inteoer 
status Reference Output Word 


Frocedures 3-Hla 


ISAMF i ndNext 


FUNCTION ISAMFindNext (fileNumber: Integers 
columnNumber: Integer: 
VAR unique: UniqueTypes; 
VAR recordID: LongInt; 
VAR status: Integer); StringPtrs 


DPERATION 


Finds the next physical record in the data file or, if the 
column identified in columnNumber is a key column, the next 
record in the sorted tey file. The "next" record is related to 
the file pointer. Each data file and key file has an indepenent 
file pointer which, when the file is first opened or after it is 
updated or after a call to ISAMResetFile, points to the first 
record, 


RecordID returns the I.D. of the record found. If the column is 
a key column, unique returns 0 if the next key is a duplicate, 1 
if it is not. When the column is not a key column, unique 
returns 2. 


FUNCTION RETURN 


Returns a pointer to the string containing the content of the 
column in the record found. 


Pass Method 


fileNumber Value Integer 


col umnNumber Value Integer 


unique Reference UniqueType* 


recordID Reference LongInt 


status Reference Word 


& A one-byte enumerated type defined to be (KeyIsUnique, 
KeyIsNotUnique, Unknown). 
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ISAMGet Status 


PROCEDURE ISAMGetStatus (fileNumber: Integer; 
VAR info: ISAMInfoType;# 
len: Integer; 
VAR status: Word); 


OPERATION 


Counts the number of key columns, the number of total columns, 
and the number of deleted or replaced records since the last 
compression. This information is returned in the info 


parameter. Specify the number of bytes to obtain from info in 
len. 


fileNumber Value Integer 


info Reference ISAMInfoTypek 


len Value Integer 


status Reference Word 


Defined to be Record 
numindexes: Byte; 
numcols: Integer; 
numDeletedRecords: Integer; 
END; 
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ISAMOpen 


PROCEDURE ISAMOpen ifileNumber: Integer; 
VAR status: Word); 


OPERATION 


Opens and allocates memory to a previously attached data file. 
You mst open a file before you can access it. 


[ Feraneter [Fass Method | in/out] Data Typel 


fileNuaber Input Integer 
Output 


PROCEDURE ISAMOpenIndex (fileNumber: Integer; 
columnNumber: Integer; 
VAR status: Word); 


Value 


status Reference 


ISAMOpen index 


OPERATION 


Opens and allocates memory to a previously created key file 
associated with a particular data file. You must open the key 
file before you can use it. 


[Parameter | Pass Method | In/Out 


fileNumber Value Integer 


col umnNumber Value Integer 


status Reference Word 
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ISAMRead 


FUNCTION ISAMRead (fileNumber: Integer; 
recordID: LongInt; 
VAR status: Word): StringPtrs 


OPERATION 


Copies the record you identify with recordID ¢rom an open data 
file to a character string that the ISAM File Manager 
establishes. 


FUNCTION RETURN 


3-14 


Returns a pointer to the string containing the data record. 
When you are through with the string, you should delete it by 


calling the procedure FreeString (see the Compass Computer 
Common Code Manual). 


Pass Method | In/Out 


fileNumber 


Value Integer 


recordID 


Value Longint 


status Reference Word 
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ISAMRep1 aceRecord 


PROCEDURE ISAMReplaceRecord (fileNumber: Integer; 
mewRecord: StringPtr; 
VAR recordID: Longint; 
VAR status: Word); 


OPERATION 


Replaces the content of a specified record in an open data file. 
You supply the new data in newRecord and you identify the record 
to be repiaced in recordID. The ISAM File Manager returns the 
new record I.D. using the same recordID parameter (it is both 
input and output). Any key file associated with the data file 
must be open so that it can be updated. 


Pass Method In/Out 


fileNumber Value Input 


newRecord Value Input 


recordID Reference Input/ LongInt 
Output 


status Reference Output Word 
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IsAMResetFile 


PROCEDURE ISAMResetFile (fileNumber: Integer; 
columnNumber: Integer; 
VAR status: Word); 


DPERATION 


Moves the file pointer to the first record in a data file or a 
key file. ‘When columnNumber is 0 or any other column number 
that does not identify a key column, the data file’s pointer is 
reset to the beginning of the data file (the next record found 
by ISAMFindNext will be the first record of the data file). 
When columnNumber identifies a key column, the pointer for that 
key file is reset to the beginning of the key file. 


Tovout_[ tata Type) 
#ileNumber Value Input Integer 


columnNumber Value Enput Integer 


status Reference Output. Word 
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APPENDIX A: STATUS PARAMETER RETURNS 


The status parameter, the last parameter for all ISAM procedures except 
ISAMExit, returns information on the successful or unsuccessful completion 
of the procedure’s work. 


In your call, provide a status variable of the data type Word to accept 
the error number (status code) passed by reference to your program. You 
may want to write code to check status and take appropriate action. 
Additionally, you can call the procedure ISAMDecodeError to return the 
message associated with the error number. 


If status is 0, the procedure completed sucessfully. If vou receive any 
other number, something has gome wrong. ISAM File Manager errors are 
listed in the table below. Operating system errors, outside of the range 
2500 - 2515, are listed in the Operating System Reference Manual. 


Status Returns A~1 


Table A-1. Status Codes and Their Messages 


Message What to Do 
<<to be added>> 


Too many attached ISAM files 
ISAM file is not attached 

ISAM file is not open 

ISAM file number is invalid 
ISAM file is already attached 
ISAM record format is invalid 
ISAM Key file already exists 
ISAM Key file doesn’t exist 
ISAM duplicate keys are invalid 
ISAM key fale is invalid 

ISAM record does nat exist 

ISAM record was not found 

ISAM record was deleted 

ISAM descriptor file is invalid 
ISAM column number is invalid 


ISAM file type is invalid 


A-2 Status Returns 


O 


APPENDIX Bs RUNNING ISAM PROGRAMS 


This appendix names the subsystem file containing ISAM run-time software, 
the file that must be loaded in order to run a program that uses the ISAM 
File Manager. 


Tt also provides names two include files, one which must be included if 
your calling program is written in Paseal-@4 and one which must be 
included if your program is written in PL/M-86. The include files contain 
the declarations of data structures, functions, and procedures. To use 
the ISAM File Manager, your application must refer ta the appropriate 
include file with the $INCLUDE statement. 


WARNING: Because a declaration in this manual may not 
always be up to date with respect to the most current 
software, vou must use the declaration from the 
include file over the declaration from the manual if 
they disagree. 

ISAM File Manager Software: ISAM. Common 

Pascal-86 include file: ISAM.PAS.INC 

PL/M-86 include file: ISAM.PLM. INC 

For complete programmer instructions, including directions for loading, 


linking. and compiling, see the Compass Computer Program Development Guide 
and the appropriate language manual. 
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